{\rtf1\ansi\ansicpg1252\cocoartf1348\cocoasubrtf170
{\fonttbl\f0\fswiss\fcharset0 Helvetica;\f1\froman\fcharset0 Times-Roman;\f2\fmodern\fcharset0 Courier;
}
{\colortbl;\red255\green255\blue255;}
\margl1440\margr1440\vieww16960\viewh16500\viewkind0
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural

\f0\fs24 \cf0 PQC - API notes\
\
Most of the API information is derived from the 
\f1\b \expnd0\expndtw0\kerning0
eBATS: ECRYPT Benchmarking of Asymmetric Systems 
\f0\b0 (https://bench.cr.yp.to/ebats.html). This has been done to facilitate benchmarking algorithm performance. Please look at the eBATS page for more information on how to submit an algorithm for performance benchmarking.  There are two sets of API calls listed for each primitive. The first set is the API call directly from the eBATS page, or something very similar for the Key Establishment section. The second set of calls is for testing purposes. The calls extend the eBATS calls for functions that utilize randomness by providing a pointer to specify a randomness string. This will allow algorithms that utilize randomness to be able to provide reproducible results.  For example, this will allow testing of KAT files.\kerning1\expnd0\expndtw0 \
\
Public-key Signatures\
See 
\f1\fs32 \expnd0\expndtw0\kerning0
https://bench.cr.yp.to/call-sign.html
\f0  
\fs24 \expnd0\expndtw0\kerning0
for more information on Public-key Signature API and performance testing.\
\
The first thing to do is to create a file called 
\i \expnd0\expndtw0\kerning0
api.h
\i0 \expnd0\expndtw0\kerning0
. This file contains the following three lines (with the sizes set to the appropriate values):\
\pard\pardeftab720

\f2\fs26 \cf0 \expnd0\expndtw0\kerning0
     #define CRYPTO_SECRETKEYBYTES 256\
     #define CRYPTO_PUBLICKEYBYTES 85\
     #define CRYPTO_BYTES 128\
\pard\pardeftab720

\f0\fs24 \cf0 \kerning1\expnd0\expndtw0 \
Then create a file called 
\i sign.c
\i0  with the following function calls:\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
\cf0 	eBATS calls\
		Generates a keypair - 
\i pk
\i0  is the public key and 
\i sk
\i0  is the secret key.\
\
\pard\pardeftab720

\f2\fs26 \cf0 \expnd0\expndtw0\kerning0
		int crypto_sign_keypair(\
			unsigned char *pk,\
			unsigned char *sk\
		)\
\
\pard\pardeftab720

\f0\fs24 \cf0 \expnd0\expndtw0\kerning0
		Sign a message: 
\i sm
\i0  is the signed message, 
\i m
\i0  is the original message, and 
\i sk
\i0  is the secret key.\
\
\pard\pardeftab720

\f2\fs26 \cf0 \expnd0\expndtw0\kerning0
		int crypto_sign(\
			unsigned char *sm, unsigned long long *smlen,\
			const unsigned char *m, unsigned long long mlen,\
			const unsigned char *sk\
		)\
\
		
\f0\fs24 \expnd0\expndtw0\kerning0
Verify a message signature: 
\i m
\i0  is the original message, 
\i sm
\i0  is the signed message, 
\i pk
\i0  is the public key.
\f2\fs26 \expnd0\expndtw0\kerning0
\
\
		int crypto_sign_open(\
			unsigned char *m, unsigned long long *mlen,\
			const unsigned char *sm, unsigned long long smlen,\
			const unsigned char *pk\
		)\
\pard\pardeftab720

\f0\fs24 \cf0 \kerning1\expnd0\expndtw0 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
\cf0 	KAT calls\
\pard\pardeftab720

\f2\fs26 \cf0 \expnd0\expndtw0\kerning0
		int crypto_sign_keypair_KAT(\
			unsigned char *pk,\
			unsigned char *sk,\
			unsigned char *randomness\
		)\
\
		int crypto_sign_KAT(\
			unsigned char *sm, unsigned long long *smlen,\
			const unsigned char *m, unsigned long long mlen,\
			const unsigned char *sk,\
			unsigned char *randomness\
		)\
\pard\pardeftab720

\f0\fs24 \cf0 \kerning1\expnd0\expndtw0 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
\cf0 \
Public-key Encryption\
See 
\f1\fs32 \expnd0\expndtw0\kerning0
https://bench.cr.yp.to/call-encrypt.html
\f0  
\fs24 \expnd0\expndtw0\kerning0
for more information on Public-key Encryption API and performance testing.\kerning1\expnd0\expndtw0 \
\expnd0\expndtw0\kerning0
\
The first thing to do is to create a file called 
\i \expnd0\expndtw0\kerning0
api.h
\i0 \expnd0\expndtw0\kerning0
. This file contains the following three lines (with the sizes set to the appropriate values):\
\pard\pardeftab720

\f2\fs26 \cf0 \expnd0\expndtw0\kerning0
     #define CRYPTO_SECRETKEYBYTES 256\
     #define CRYPTO_PUBLICKEYBYTES 64\
     #define CRYPTO_BYTES 48\
\pard\pardeftab720

\f0\fs24 \cf0 \kerning1\expnd0\expndtw0 \
Then create a file called 
\i encrypt.c
\i0  with the following function calls:\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
\cf0 	eBATS calls\
		Generates a keypair - 
\i pk
\i0  is the public key and 
\i sk
\i0  is the secret key.\
\
\pard\pardeftab720

\f2\fs26 \cf0 \expnd0\expndtw0\kerning0
		int crypto_encrypt_keypair(\
			unsigned char *pk,\
			unsigned char *sk\
		)\
\
\pard\pardeftab720

\f0\fs24 \cf0 \expnd0\expndtw0\kerning0
		Encrypt a plaintext: 
\i c
\i0  is the ciphertext, 
\i m
\i0  is the plaintext, and 
\i pk
\i0  is the public key.
\f2\fs26 \expnd0\expndtw0\kerning0
\
\
		int crypto_encrypt(\
			unsigned char *c,unsigned long long *clen,\
			const unsigned char *m,unsigned long long mlen,\
			const unsigned char *pk\
		)\
\

\f0\fs24 \expnd0\expndtw0\kerning0
		Decrypt a ciphertext: 
\i m
\i0  is the plaintext, 
\i c
\i0  is the ciphertext, and 
\i sk
\i0  is the secret key.
\f2\fs26 \expnd0\expndtw0\kerning0
\
\
		int crypto_encrypt_open(\
			unsigned char *m,unsigned long long *mlen,\
			const unsigned char *c,unsigned long long clen,\
			const unsigned char *sk\
		)
\f0\fs24 \kerning1\expnd0\expndtw0 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
\cf0 \
	KAT calls\
\pard\pardeftab720

\f2\fs26 \cf0 \expnd0\expndtw0\kerning0
		int crypto_encrypt_keypair_KAT(\
			unsigned char *pk,\
			unsigned char *sk,\
			unsigned char *randomness\
		)\
\
		int crypto_encrypt_KAT(\
			unsigned char *c,unsigned long long *clen,\
			const unsigned char *m,unsigned long long mlen,\
			const unsigned char *pk,\
			unsigned char *randomness\
		)\
\pard\pardeftab720

\f0\fs24 \cf0 \kerning1\expnd0\expndtw0 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
\cf0 \
Key Establishment\
The calls in the eBATS specification do not meet the calls specified in the call for algorithms. However, attempts were made to match the specifications for the other algorithms. (For reference, see 
\f1\fs32 \expnd0\expndtw0\kerning0
https://bench.cr.yp.to/call-dh.html
\f0  
\fs24 \expnd0\expndtw0\kerning0
for more information on Public-key Diffie-Hellman API and performance testing.)\kerning1\expnd0\expndtw0 \
\expnd0\expndtw0\kerning0
\
The first thing to do is to create a file called 
\i \expnd0\expndtw0\kerning0
api.h
\i0 \expnd0\expndtw0\kerning0
. This file contains the following three lines (with the sizes set to the appropriate values):\
\pard\pardeftab720

\f2\fs26 \cf0 \expnd0\expndtw0\kerning0
     #define CRYPTO_SECRETKEYBYTES 192\
     #define CRYPTO_PUBLICKEYBYTES 64\
     #define CRYPTO_BYTES 64
\f0\fs24 \kerning1\expnd0\expndtw0 \
\
Then create a file called 
\i keyestablishment.c
\i0  with the following function calls:\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
\cf0 	eBATS-like calls\
\pard\pardeftab720

\f2\fs26 \cf0 \expnd0\expndtw0\kerning0
\
\pard\pardeftab720

\f0\fs24 \cf0 \expnd0\expndtw0\kerning0
		Generate an 
\i initiator
\i0  key-establishment message: 
\i kei
\i0  is the 
\i initiator\'92s
\i0  key exchange message and 
\i ski
\i0  is the secret key of the 
\i initiator
\i0 .
\f2\fs26 \expnd0\expndtw0\kerning0
\
\
		int crypto_keyestablishment_initiator_generate(\
			unsigned char *kei,\
			unsigned char *ski\
		)\
\

\f0\fs24 \expnd0\expndtw0\kerning0
		Generate a 
\i responder
\i0  key-establishment message: 
\i ker
\i0  is the responder\'92s key exchange message, 
\i \kerning1\expnd0\expndtw0 skr 
\i0 is the 
\i responder\'92s 
\i0 secret key, and
\i  kei i
\i0 s the 
\i initiator\'92s
\i0  key exchange message\expnd0\expndtw0\kerning0
.
\f2\fs26 \expnd0\expndtw0\kerning0
\
\
		int crypto_keyestablishment_responder_generate(\
			unsigned char *ker,\
			unsigned char *skr,\
			const unsigned char *kei\
		)\
\

\f0\fs24 \expnd0\expndtw0\kerning0
		
\i Initiator
\i0  recovery of the shared secret: 
\i ss
\i0  is the shared secret, 
\i \kerning1\expnd0\expndtw0 ker
\i0  is the 
\i responder\'92s
\i0  key exchange message, and 
\i ski
\i0  is secret key of 
\i initiator
\i0 \expnd0\expndtw0\kerning0
.
\f2\fs26 \expnd0\expndtw0\kerning0
\
\
		int crypto_keyestablishment_initiator_recover(\
			unsigned char *ss,\
			const unsigned char *ker,\
			const unsigned char *ski\
		)\
\

\f0\fs24 \expnd0\expndtw0\kerning0
		
\i Responder
\i0  recovery of the shared secret: 
\i ss
\i0  is the shared secret, 
\i \kerning1\expnd0\expndtw0 kei
\i0  is the 
\i initiator\'92s 
\i0  key exchange message, and 
\i skr
\i0  is secret key of 
\i responder
\i0 \expnd0\expndtw0\kerning0
.
\f2\fs26 \expnd0\expndtw0\kerning0
\
\
		int crypto_keyestablishment_responder_recover(\
			unsigned char *ss,\
			const unsigned char *kei,\
			const unsigned char *skr\
		)\
\pard\pardeftab720

\f0\fs24 \cf0 \kerning1\expnd0\expndtw0 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
\cf0 	KAT calls
\f2\fs26 \expnd0\expndtw0\kerning0
\
\pard\pardeftab720
\cf0 \expnd0\expndtw0\kerning0
\
		int crypto_keyestablishment_initiator_generate_KAT(\
			unsigned char *kei,\
			unsigned char *ski,\
			unsigned char *randomness\
		)\
\
		int crypto_keyestablishment_responder_generate_KAT(\
			unsigned char *ker,\
			unsigned char *skr,\
			const unsigned char *kei,\
			unsigned char *randomness\
		)\
\pard\pardeftab720

\f0\fs24 \cf0 \kerning1\expnd0\expndtw0 \
}